Skip to content

feat: local pubky swaps provider - #39

Merged
ovitrif merged 5 commits into
mainfrom
feat/pubky-swap-provider
Nov 13, 2026
Merged

ovitrif merged 5 commits into
mainfrom
feat/pubky-swap-provider

Conversation

@ovitrif

@ovitrif ovitrif commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Refs:

Description

  • Adds a Pubky Swaps provider as the pubky-swap service (profile pubky-swaps), so the apps' swap route journeys (paykit-swap-route.xml, J1, and paykit-swap-restore.xml, J2) run on this stack. Until now they needed the provider built and run by hand next to the stack.
  • Builds coreyphillips/pubky-swap at f45e204 with the full feature set. That's the commit bitkit-core's Pubky Swaps client pins (swap-common in its Cargo.toml at v0.8.0-rc15). PUBKY_SWAP_REV moves it.
  • The provider shares LND's network namespace, so it dials LND's gRPC on 127.0.0.1:10009 with the TLS cert and admin macaroon LND writes to ./lnd, mounted read-only. It reads the chain from electrs:60001, and waits for LND's macaroon on a fresh stack.
  • Its offer is the one the journeys were recorded with:
    • 10,000 to 1,000,000 sats, submarine and reverse;
    • base fee 100 sats, 2,500 ppm, one confirmation;
    • no homeserver, so a wallet finds it only among its contacts and reaches it over iroh by its pubky.
  • Its Pubky identity is a throwaway BIP39 phrase. A small pubky-swap-keygen binary writes it to the pubky_swap_data volume on first start. No phrase is in the repository, and the pubky stays the same across restarts, so the contact a wallet saved keeps working.
  • README "Pubky Swaps" has the recipe: start and fund the stack, start the provider, read its pubky, bring up the marketplace and payment-request fixtures, and set up the wallet for J1 and J2.

Out of Scope

QA Notes

Automated Checks

  • docker compose config -q: passes.
  • docker compose --profile pubky-swaps build pubky-swap: builds swap-provider at f45e204 and the keygen.
  • DOCKER_BUILDKIT=0 docker build pubky-swap: builds with the classic builder, as on the QA boxes.

Manual Tests

@ovitrif ovitrif self-assigned this Nov 13, 2026
@ovitrif
ovitrif requested a review from piotr-iohk November 13, 2026 09:36

@piotr-iohk piotr-iohk left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

QA review

Scope: full review of the whole PR diff against its merge base (96b597c), at 7afbeff. No earlier QA baseline exists. Covered: the pubky-swap compose service, the Dockerfile, the entrypoint, the keygen crate, and the README/CHANGELOG recipe.

1 actionable finding — resolve or provide an evidence-backed rebuttal.

The provider wiring matches its dependencies. I checked it against coreyphillips/pubky-swap@f45e204:

  • Every swap-provider flag in entrypoint.sh exists.
  • PUBKY_SWAP_RECOVERY_PHRASE__FILE is read and the first line is trimmed.
  • --no-homeserver together with the default iroh rendezvous is a supported combination.
  • The provider opens no TCP listener in LND's network namespace (the status API is off).
  • bitkit-core v0.8.0-rc15 pins the same swap-common revision.
  • The LND cert and macaroon paths match the ./lnd:/home/lnd/.lnd mount and the LND 0.18 regtest layout.
  • The README ports, the ./bitcoin-cli send … -m usage and the fixture service names match the repo.

The one finding: the Dockerfile's cache mounts need BuildKit. The repo's own scripts say the QA boxes don't have BuildKit, and the README builds the image straight through compose.

Validation: source analysis only. The PR reports no CI checks. Limits:

  • I could not build the keygen crate locally: the sandbox denied network access to crates.io.
  • I did not run a Docker build or start the stack.
  • J1/J2 journey results are still pending from the author.

Suggested additional test cases

  • Host with Docker but no buildx/BuildKit (the QA-box setup): run the README recipe through docker compose --profile pubky-swaps up -d --build pubky-swap. Expected: the image builds and the provider logs its pubky. If it fails with a --mount / BuildKit error, the finding is confirmed.
  • Running stack: docker compose --profile pubky-swaps restart pubky-swap, then compare docker compose logs pubky-swap | grep "Provider pubky" before and after. Expected: the pubky is the same. After docker compose rm -sf pubky-swap && docker volume rm <project>_pubky_swap_data and a fresh up, the pubky should change.
  • Fresh ./lnd directory (no macaroon yet): start pubky-swap together with lnd. Expected: it logs waiting for LND's macaroon until LND writes it, then Connected to LND node, with no crash loop.

Findings

  • [MEDIUM] Provider image can't build on the QA boxes' Docker (no BuildKit) — inline at pubky-swap/Dockerfile:10.

Reviewer model: claude-opus-5-5
Reasoning effort: high

Comment thread pubky-swap/Dockerfile Resolved
@talosmachina

Copy link
Copy Markdown

1 finding (P3). Adds a pubky-swaps profile that builds swap-provider at the f45e204 bitkit-core pins and runs it on the stack's LND and Electrum. Reviewed 7afbeff, full tier. Nothing was built or run here: talos-pr-run refused on the permission check, so this is a static review.

README.md:57-65 The pubky-swap service is missing from the Services list, where the neighbouring fixture profiles sit (marketplace, payment-requests, spark). The provider is the counterparty a reader looks for after the swap route journeys are mentioned, and the only place they will find it is the section at line 729. One bullet beside the payment-requests one.

What I checked, and 8 candidates I ruled out

Read in full: docker-compose.yml (the new service and its surroundings), pubky-swap/Dockerfile, pubky-swap/entrypoint.sh, pubky-swap/keygen/{Cargo.toml,src/main.rs}, the README section, CHANGELOG.md

Ruled out

  • Flags that the pinned binary does not have: every flag the entrypoint passes exists on swap-provider's Cli at f45e204 (--network, --directions, --min-amount, --max-amount, --base-fee, --fee-ppm, --confirmations, --wallet, --lnd-address, --lnd-cert, --lnd-macaroon, --electrum-url, --data-dir, --no-homeserver), and submarine,reverse parses through parse_directions (swap-provider/src/lib.rs:584).
  • --no-homeserver at startup: a homeserver-free provider refuses --broadcast-offer (swap-provider/tests/no_homeserver_cli.rs:38), which the entrypoint does not pass, so the offer is advertised locally and the doorbell, which the flag requires, stays on by default.
  • The identity file: PUBKY_SWAP_RECOVERY_PHRASE__FILE takes the first line, trimmed (swap-config/src/lib.rs:101), and umask 077 creates it 0600, above the warn_if_world_readable threshold, so no warning on every start.
  • The LND paths: sharing LND's namespace makes 127.0.0.1:10009 LND itself, and /lnd/tls.cert and /lnd/data/chain/bitcoin/regtest/admin.macaroon match the ./lnd:/home/lnd/.lnd/ mount; the same two paths are already read-only in lnurl-server-fixture, so the mount is the house pattern.
  • A dead namespace after lnd restarts: docker compose restart lnd restarts the dependent too. Tested with a two-service probe (network_mode: service: + a loopback reachability check): the child restarted and kept connectivity.
  • Build prerequisites: protobuf-compiler covers the LND protos, the lock carries no openssl-sys so ca-certificates alone is right at runtime, and git fetch --depth 1 <url> <full-sha> against that repository works (ran it).
  • The pin: f45e204ee7646dc91983d90e4782d40760b6c72b is what bitkit-core v0.8.0-rc15 pins for swap-common, so the provider and the client are the same code.
  • The recipe's fixture step: ./pubky-marketplace up builds the fixture image at the pinned rev (ensure_fixture), so --no-build fixture-issuer rc56-peer resolves, and /health returns pubky as the app key (payment-requests/src/main.rs:324), so jq -r .pubky yields the contact a wallet saves.

Not verified: the image build and the journeys. The build rests on the QA note; the runtime log lines quoted there are what the code emits (Provider pubky, Connected to LND node, Provider is execution-capable, iroh rendezvous online, and the three reverse-swap lines).

Merge confidence: 4/5, the image build was not run in this review.

@ovitrif

ovitrif commented Nov 13, 2026

Copy link
Copy Markdown
Collaborator Author

@talosmachina added in 491a491: the Services list now has a "Pubky Swaps provider" bullet beside the other opt-in profiles.

@ovitrif
ovitrif requested a review from piotr-iohk November 13, 2026 09:56
@talosmachina

Copy link
Copy Markdown

@ovitrif confirmed in 491a491: the Services list in README.md now carries the "Pubky Swaps provider" bullet with the pubky-swaps profile, in the same shape as the other opt-in fixtures. That closes my finding. The same commit drops the BuildKit cache mounts from pubky-swap/Dockerfile, which reads correctly for the classic builder. I did not build it here.

@ovitrif

ovitrif commented Nov 13, 2026

Copy link
Copy Markdown
Collaborator Author

J1 (paykit-swap-route.xml) and J2 (paykit-swap-restore.xml) pass on both apps against this PR's stack, with the provider started by docker compose --profile pubky-swaps up -d pubky-swap:

In each J1, the provider's claim spends only its HTLC and pays exactly 0.0002 BTC to the fixture-issuer's address. In each J2, a wallet restored mid-swap claims the 20,000 sats to its own Savings. Both apps found the provider only among the wallet's contacts.

@ovitrif

ovitrif commented Nov 13, 2026

Copy link
Copy Markdown
Collaborator Author

80ebc3d adds an "Issuer contact" step to the README's Pubky Swaps recipe. J1 pays the fixture-issuer as a saved contact, which works only once the issuer is linked to the wallet and has sent it its private payment list (/link, /sync, then /endpoints with restore for the wallet). Without the list, the app shows that the contact hasn't enabled payments.

With main merged in (the rc8 issuer from #38), J1 via the saved contact now passes on both apps:

@piotr-iohk piotr-iohk left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

QA review

Scope: Re-reviewed the full PR at 80ebc3d after the comparison base changed to 54e7def and no coverage baseline was supplied. This pass covered the full diff from that merge base.

1 actionable finding — resolve or provide an evidence-backed rebuttal.

The pubky-swaps service matches pubky-swap f45e204, the swap-common revision pinned by bitkit-core v0.8.0-rc15. --wallet lnd overrides the BDK wallet default, the Lightning backend already defaults to LND, and the TLS cert and admin macaroon paths match this stack's ./lnd layout. Electrum tcp://electrs:60001 is reachable through LND's network namespace. The recovery phrase is written once into pubky_swap_data, and that revision trims the file's first line, so the logged pubky stays stable across provider restarts. The offer flags, startup log text, and issuer /link, /sync, and /endpoints steps match the provider and the payment-request fixture.

Validation: cargo build --locked for pubky-swap/keygen succeeded with rustc 1.83.0. Docker is not available in this environment, so docker compose config, the provider image build, and a running stack were not executed. The author's reported compose build and manual startup were not re-run.

Suggested additional test cases

  • Docker, fresh volumes, with Electrum not already accepting connections. Run docker compose --profile pubky-swaps up -d as the first command. Expected: pubky-swap logs Provider is execution-capable. It does not log chain watcher unavailable or stay up as negotiation-only. The entrypoint waits only for LND's macaroon, and this provider revision connects to Electrum once at startup.

Earlier findings reconciled at this revision: 2 verified fixed.

Findings

  • [LOW] Swap journey links point at master, where the files are absent — inline at README.md:732.

Reviewer model: grok-4.7
Reasoning effort: high

Comment thread README.md Resolved
@ovitrif

ovitrif commented Nov 13, 2026

Copy link
Copy Markdown
Collaborator Author

@piotr-iohk 7ae2cec also takes the suggested fresh-volume case. The entrypoint now waits for Electrum on electrs:60001 as well as for LND's macaroon, because this provider revision connects to Electrum once at startup and otherwise stays negotiation-only. On a running stack, the wait passes when Electrum is up and keeps waiting on a closed port. I didn't rerun a full fresh-volume start.

@ovitrif
ovitrif requested a review from piotr-iohk November 13, 2026 13:00

@piotr-iohk piotr-iohk left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

QA review

Scope: Follow-up of 7ae2cec since 80ebc3d, merge base 54e7def. Baseline: pullrequestreview-5891318225. This pass inspected the Electrum wait and the README journey-location sentence. Inherited coverage: the pubky-swaps compose service (profile, LND network namespace, read-only ./lnd mount, pubky_swap_data volume); the f45e204 image build with feature full and the keygen crate; entrypoint flags, recovery-phrase file, and LND macaroon wait; the README Pubky Swaps recipe against this stack's LND, Electrum, lnurl-pay channel fixture, and fixture-issuer /link /sync /endpoints; and the bitkit-core v0.8.0-rc15 swap-common pin with paykit-swap-route.xml on app master versus the open app PR heads.

No new actionable code findings.

At pubky-swap f45e204, build_chain connects once during run. A failed connect leaves the process up and rejecting swap requests for the rest of that process. The new loop waits for TCP electrs:60001, the same endpoint as --electrum-url, inside the LND network namespace the service already uses. Debian Bookworm bash 5.2.15, the bash shipped in debian:bookworm-slim, implements /dev/tcp; a refused connection exits non-zero and the loop retries. The README sentence matches the apps: journeys/paykit-swap-route.xml and journeys/paykit-swap-restore.xml are on bitkit-ios#1170 at 58139bc5 and bitkit-android#1732 at a786e349. Both app masters' journeys/ listings have neither file.

Validation: sh -n pubky-swap/entrypoint.sh passed at 7ae2cec. Bookworm package bash_5.2.15-2+b13 was executed here: opening /dev/tcp/127.0.0.1/1 exited 1 with Connection refused. Provider startup was read at f45e204. An issue search on synonymdev/bitkit-docker for this wait found no match. The compose stack was not started (code-only; Docker is not installed). Pinned digest 3783cc01769c is the official bookworm-slim image index; its rootfs was not extracted layer by layer.

Suggested additional test cases

  • Platform: Docker host running this stack. Setup: docker compose up -d, then docker compose stop electrs, with LND already past its macaroon. Action: docker compose --profile pubky-swaps up -d pubky-swap, watch docker compose logs -f pubky-swap, then docker compose start electrs. Expected: logs print waiting for Electrum until Electrum accepts electrs:60001, then Provider is execution-capable (LND + chain watcher + funding wallet present).

Earlier findings reconciled at this revision: 2 verified fixed.

Reviewer model: grok-4.7
Reasoning effort: high

@ovitrif

ovitrif commented Nov 13, 2026

Copy link
Copy Markdown
Collaborator Author

Merging: approved at 7ae2cec, no open threads, and main has nothing this PR lacks. The swap journeys on synonymdev/bitkit-android#1732 and synonymdev/bitkit-ios#1170 point their QA setup at this recipe.

@ovitrif
ovitrif merged commit 3233467 into main Nov 13, 2026
@ovitrif
ovitrif deleted the feat/pubky-swap-provider branch November 13, 2026 16:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants